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This publication describes the ibjob Processor Debug- 
ging Package. The debugging package is a program- 
ming aid that enables the user to obtain dynamic 
dumps of specified areas of core storage and machine 
registers during program execution. The package con- 
tains two separate facilities: Compile-Time Debugging 
for cobol programs and Load-Time Debugging for 
Fortran iv and map programs. Load- time debug re- 
quests are processed by the ibjob Debugging Processor 
(ibdbl), #7090-PR-807. Compile-time debug requests 
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Preface 



The ibm 7090/7094 ibjob Processor Debugging Pack- 
age provides a means of taking highly selective dumps 
of core storage areas and machine registers with a min- 
imum of programming effort. By carefully selecting the 
areas to be dumped and the time at which to dump 
them, the user can obtain valuable information for lo- 
cating and correcting program errors. The facilities de- 
scribed in this publication pertain to Fortran iv, cobol, 
and map program debugging. 

As a prerequisite to understanding this publication, 
the reader should be familiar with the ibjob Processor, 
as described in the ibm publication IBM 7090/7094 
IBSYS Operating System: IBJOB Processor, Form 
C28-6275, and with at least one of the programming 
languages accepted by the processor, as described in 
the ibm publications: 
IBM 7090/7094 Programming Systems: Macro As- 
sembly Program (MAP) Language, Form C28-6311 
IBM 7090/7094 Programming Systems: FORTRAN 

IV Language, Form C28-6274 
IBM 7090/7094 Programming Systems: COBOL 

Language, Form J28-6260 
The compile-time debugging language ( for use with 
cobol programs ) is based on cobol, and the load-time 
debugging language ( for use with both Fortran iv and 
map programs ) is based on Fortran rv. The map pro- 
grammer who is totally unfamiliar with Fortran 
should be able to use all of the facilities described 
herein with limited reference to the Fortran language 
publication listed above. 

The 7090/7094 ibjob Processor Debugging Package 
requires the same minimum machine configuration as 
the 7090/7094 ibjob Processor except that a unit speci- 
fied as sysck2 is required for debugging output when 
the load-time debugging facility is used. 

The problem of locating errors in programs rapidly 
and efficiently is of major concern to all computer users. 
The 7090/7094 ibjob Processor Debugging Package 
meets this problem by allowing the programmer to ma- 
nipulate data, control processing, or dump the contents 



of any relevant areas by inserting debug requests at 
key points in his program. To use the debugging pack- 
age, the programmer writes a debug request in the ap- 
propriate debugging language. Each request specifies 
the point(s) in the program at which the specified ac- 
tion is to be taken. Any reasonable number of requests 
may be given for a single program. 

The debugging package provides two types of de- 
bugging. The first, compile-time debugging, is included 
with ibcbc at compilation to specify dumps at various 
points in a cobol source program. In this type, the text 
of debug requests is similar to the cobol language. The 
second type, load-time debugging, uses the capabilities 
of ibmap and ibldr to provide debugging during the 
execution of a Fortran iv or map program without re- 
compilation or reassembly. In this type, the text of 
debug requests is written in a form similar to the 
Fortran iv language. 

This publication describes the debugging package in 
two parts : Part i describes the compile-time facility for 
cobol programs; Part n describes the load-time facility 
for Fortran iv and map programs. These parts are in- 
dependent of each other, so that reference to one is not 
required when reading the other. The material in Part n 
is divided into two sections, "Load-Time Debug Re- 
quests" and "Additional Load-Time Debugging Fea- 
tures." The Fortran iv programmer will generally use 
only the facilities described in the first section, whereas 
the map programmer will use the facilities described in 
both sections. 

The following conventions apply to all card formats 
given in this publication: 

1. Brackets [ ] indicate that the enclosed material 
may be omitted. 

2. Braces { } indicate that a choice of the enclosed 
material is to be made by the user. 

3. Upper-case words, if used, must be present in the 
form indicated. 

4. Lower-case words represent generic quantities 
whose values must be supplied by the user. 



Major Revision (June, 1964) 

This publication, Form C28-6362-1, makes the previous edition, 

Form C28-6362-0, obsolete. 
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The compile-time facility of the debugging package 
enables the cobol programmer to specify debug re- 
quests with his source-language program. The requests 
are compiled with the source program and are exe- 
cuted at object time. The text of the request is very 
similar to the procedural text of cobol. In addition, a 
special count-conditional statement is provided. Since 
procedural capabilities of the cobol compiler are avail- 
able, a user can be highly selective in specifying what 
is to be dumped. He can manipulate and test the val- 
ues of data items in his program and dump only perti- 
nent and meaningful information, without affecting 
execution of the program itself. 



Compile-Time Debugging Packet 

All compile-time requests for a given program are 
grouped together into a debugging packet. The com- 
pile-time debugging packet is placed immediately 
following the $cbend card of the associated source 
program. 

Compile-Time Debug Requests 

Each compile-time debug request is headed by the 
control card $ibdbc. The sibdbc card serves two func- 
tions: it identifies individual requests, and it defines 
the point at which the request is to be executed. The 
general form of this card is 

1 8 16-72 

$IBDBC [name] location [, FATAL] 

where the parameters are described as follows: 

name An optional user-assigned control section name, 

which permits deletion of the request at load 
time. This name must be a unique control sec- 
tion name consisting of up to six alphabetic 
and/or numeric characters, at least one of which 
must be alphabetic. 

location The COBOL section-name or paragraph-name 

(qualified, if necessary) indicating the point in 
the program at which the request is to be ex- 
ecuted. Effectively, debug request statements 
are performed as if they were physically placed 
in the source program following the section- or 
paragraph-name, but preceding the text associ- 
ated with the name. 

FATAL If this option is exercised, loading and execution 

of the object program will be prevented when- 
ever an error of level E or greater occurs within 
a debug request statement. If FATAL is not 
specified, a COBOL error of level E or less, 
when encountered in the procedural text of a 
debug request, will not prevent loading and 



execution of the object program. Instead, an 
attempt will be made to interpret the statement. 
If interpretation is impossible, the erroneous 
statement (but not the entire request if it con- 
sists of more than one statement) will be dis- 
carded. 

The text of the debug request follows immediately 
after the $ibdbc card. The text mav consist of anv valid 
procedural statements conforming to the requirements 
of the cobol language and format and of the count- 
conditional statement described in the following text. 
The only restriction on these statements is that they 
may not transfer control outside of the debug request 
itself. A procedure-name in a debug request must be 
unique to the request in which it appears, to all other 
debug requests, and to the source program. Display 
statements in a debug request write on sysoui. 

A compile-time debug request is terminated by an 
end-of-file card, another sibdbc card, or a $-control 
card. 

Count-Conditional Statement 

A count-conditional statement, available for use only 
in debug requests, provides the programmer with a 
means of qualifying the time when a debugging action 
should be taken. The count-conditional statement has 
the same structure as the cobol if statement (condi- 
tional, true option, false option) and may be used in 
the same manner; i.e., it may be nested within other 
count-conditional or if statements and may have other 
count-conditional or if statements nested within it. The 
general form of the count-conditional statement is 
ONm [AND EVERY n2] [UNTIL nj statement-1 



{ ELSE ) 

} OTHERWISE J 



statement 



-] 



where n i5 n 2 , and n 3 are positive integers. If the and 
every n 2 option is not specified, but the until n 3 
option is specified, n 2 is assumed to be one. The until 
option means up to but not including the n 3 th time. 

Some examples of the count-conditional statement 
follow: 

ON 3 DISPLAY A. 

On the third time through the count-conditional state- 
ment, A is displayed. No action is taken at any other 
time. 

ON 4 UNTIL 8 DISPLAY A. 

On the fourth time through the seventh time, A is dis- 
played. No action is taken at any other time. (This 
example implies, and has the same effect as, the state- 
ment ON 4 AND EVERY 1 UNTIL 8 DISPLAY A.) 

ON 5 AND EVERY 3 UNTIL 12 DISPLAY A. 

On the fifth, eighth, and eleventh times through the 
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count-conditional statement, A is displayed. No action 
is taken at any other time. 

ON 3 AND EVERY 2 DISPLAY A. 

A is displayed on the third, fifth, seventh, ninth, etc., 
times. On the first, second, fourth, sixth, etc., times, no 
notion is i"3_lcfTi 

ON 2 AND EVERY 2 UNTIL 10 DISPLAY A ELSE 

DISPLAY B. 

On the second, fourth, sixth, and eighth times, A is dis- 
played. B is displayed at all other times. 

A Compile-Time Debugging Packet 

The numbers given in the left-hand column of the 
example in Figure 1 are for purposes of reference in 
the explanations that follow; they are not part of the 
requests themselves. The numbers in the first line 



$IB0BC A 

ON 1 AND EVERY 3 UNTIL 8 DISPLAY 

•Z=« Z. 
$IBDBC CNTRL B OF C 

IF S UNEQUAL TO T DISPLAY 'S=' S, 

MOVE T T3 S. DISPLAY • T= • T. 
$IBDBC D, FATAL 

IF V GREATER THAN VMAX ON 1 UNTIL 

10 DISPLAY 'V OUT OF RANGE, V=' V 

ELSE STOP KUN. 

Figure 1. Example of a Compile-Time Debugging Packet 



across indicate the card columns in which the various 
fields begin. 

In the first request, on the first, fourth, and seventh 
time that control passes through point A in the pro- 
gram, Z is displayed (in its own format) with the iden- 
tifying heading Z =. 

In the second request, the value of T ( with the iden- 
tifying heading T = ) is displayed at the point in the 
program identified as b of c. Also, if S is unequal to T, 
S is also displayed and its value is adjusted to the value 
of T. If desired, this debug request may be deleted 
during this and/or subsequent runs by using a $omit 
control card, which is described in the publication IBM 
7090/7094 IBSYS Operating System: IBJOB Processor, 
Form C28-6275. 

Execution of the third request causes both the mes- 
sage v out of range, v = and the value of V to be dis- 
played the first nine times that V is greater than vmax 
when program control passes through point D. On the 
tenth time, this request causes an exit from the program 
(i.e., else stop run). The fatal option on the $ibdbc 
card heading this request prohibits loading of the 
source program if the compiler encounters an error of 
level E or greater in the text of this request. 
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The load-time facility of the debugging package pro- 
vides Fortran iv and map programmers with the means 
to insert debug requests at load time to be executed 
with the object program, map object programs in- 
clude those generated by ibcbc and ibftc, as well as 
those written in map itself. Thus, the cobol program- 
mer may, if desired, take advantage of the load-time 
facility and debug from an assembly listing of his pro- 
gram; the Fortran rv programmer may also use the 
load-time facility at the map level. 

The debugging language used with the load-time 
facility is derived from the Fortran iv language, with 
changes and additions made for debugging purposes. 
The statements available in the debugging language 
permit the programmer a high degree of flexibility in 
obtaining meaningful data in his dumps. It is possible 
to perform arithmetic operations on object time and 
debug packet values, to test and manipulate results, 
and to select the quantities to be dumped. Also, the 
programmer can reference symbols appearing in the 
source program by selecting the appropriate dictionary 
option in his source program. 

In the discussions that follow, the term "integer" is to 
be interpreted as follows: if it is prefixed with a leading 
zero and does not contain any invalid octal characters 
(i.e., 8 or 9), it will be considered octal. Otherwise, it 
will be considered decimal. 



Load-Time Debugging Packet 

All of the load-time debug requests for a particular 
job run (which may consist of any configuration of 
Fortran, cobol, or map source and/or object decks) 
are grouped together into what is called the debugging 
packet. The packet is headed by a $ibdbl card and ter- 
minated by an *dend card. These control cards are de- 
scribed in the publication IBM 7090/7094 IBSYS Oper- 
ating System: IB JOB Processor, Form C28-6275.:The 
load-time debugging packet is placed at the beginning 
of the job deck, preceding the source and/or object 



Load-Time Debug Requests 

A debug request is a set of actions to be performed at 
an indicated point in the program called the insertion 
point. Each load-time debug request is headed by the 
*debug card, which identifies individual requests and 
specifies the insertion point(s) of the request in the 
program. 



The general form of the *debug card is : 

1 8 16-72 

*DEBUG [deckname] loci [, loc2, loc3, . . .] 

Blanks may be included in the variable field for legi- 
bility but they may not be imbedded. Trie parameters 
of the *debug card are as follows: 

deckname The name of the object deck to which this de- 

bug request applies. If this field is blank, the 
last deckname specified on the preceding *DE- 
BUG or *REDEF card is assumed; if a deck- 
name was not previously specified, the request 
is deleted. 

loci, . . . The location(s) of the executable instruction(s) 

at which this debug request is to be inserted. A 
location may be specified in any of the following 
ways: 

1. A statement number (FORTRAN only). 

2. A symbol. Symbols used in debug requests 
may not contain parentheses. 1 

3. A symbol ±: an unsigned decimal integer. 

4. =R followed by an unsigned octal integer 
for a relative location (i.e., relative to the 
load address of the deck). 

5. =A followed by an unsigned octal integer 
for an absolute location. 

6. An internal formula number of a FOR- 
TRAN statement with the suffix A (e.g., 
10A). 2 

Because of the method by which insertions are 
made in the program (i.e., the STR instruction), 
the programmer should take care not to specify 
insertion points at instructions whose prefix 
might be modified during execution. This is pri- 
marily of concern to the MAP programmer. 
Violation of this rule may result in unpredict- 
able results and ^ or a ri tion c . N^ ^}^^^i^ ie -moric* 
for this condition. 

The debug request is executed as if it had been phys- 
ically inserted in the deck at the specified location(s). 
The debug request action occurs before the execution 
of any action indicated by the statement or instruction 
at that location. 

The variable field of an *debug card may be extended 
over more than one card by punching cards following 
the first as shown: 



1 
*ETC 



16-72 

extension of variable field 



Immediately following the *debug card is the text of 
the request itself. If an invalid or erroneous action is 
specified in the text, that action is deleted. The text 
consists of procedural statements written in the For- 
tran format. At least one blank should follow each 



iThis restriction applies only to symbols that are explicitly given in a 
request. Symbols of this type may appear in the debugging dictionary, 
and the *REDEF card (discussed later) provides a means of renaming 
them so that they may be used in requests. 

2 The internal formula number can be referenced only when the full 
debugging dictionary has been requested. 
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statement verb (e.g., DUMpbx). 3 These statements are 
derived from the Fortran iv language, with additions 
and changes made for debugging purposes. The per- 
missible statements are: 

STOP statements 

PAUSE statements 

CALL statements 

RETURN statements 

Unconditional GO TO statements 

SET (arithmetic) statements 

Logical IF statements 

ON statements 

DUMP statements 

LIST statements 

NAME statements 

Comment cards having a C in column 1 are allowed. 

The operator ^^(exponentiation) and functions are 
not allowed, nor are references to the dummy variables 
of functions and subroutines. 

Debugging Control Statements 

The stop statement terminates execution. 

The pause statement prints the message "debug re- 
quest pause" and then the machine halts; pushing 
start restarts processing at the next debug statement. 

The call statement is used in calling subroutines. It 
has the form: 

GALL SUBR 

or 
CALL SUBR (argi, arg 2 , . . .)' 

The call cannot induce overlay. Machine registers 
are saved upon entry to the call and restored upon 
exit from the call. Machine registers that are initially 
available in the call differ from those that are saved. 

The return statement causes a return to the inter- 
rupted program; there is an implicit return at the end 
of each debug request. 

The statement go to n, where n is a decimal integer, 
is an unconditional transfer to the debugging statement 
having the corresponding integer (statement number) 
n in columns 1-5. Statement numbers used in an uncon- 
ditional go to statement must refer to statements within 
the debugging packet, not to statement numbers in the 
deck being debugged. 

SET (Arithmetic) Statement 

The set statement provides the programmer with arith- 
metic capabilities within a debug request. The general 
form of this statement is 

SETs 
where s is any valid Fortran iv arithmetic statement 
not containing functions, the ** (exponentiation) opera- 
tor, nor the logical constants .true, and .false.. Be- 
cause Fortran iv conventions override map notation, 
those map symbols that would be incorrectly treated in 

3 However, unlike FORTRAN IV, the debugging routine treats blanks in 
a statement as terminators. Therefore, no blanks may be imbedded in a 
character string that is to be treated as a single symbol. 



an arithmetic statement (e.g., 1.2) should be redefined 
prior to use. See the explanation of the *redef card for 
details of the redefining facility. 

Logical IF Statement 

The debugging logical if statement is similar to that of 
Fortran iv, with certain additions and restrictions. The 
general form of this statement is: 

IF (t) s 

or 
IFbtbs 

where b represents one or more blanks, t is any logical 
expression not containing function calls or the ** oper- 
ator, and s is an unconditional executable statement or 
an on statement followed by an unconditional execut- 
able statement. 

The permissible logical operators (where b repre- 
sents a blank and x and y are logical expressions) are: 

bNOTbx or b .NOT. bx 

xbANDby or xb .AND. by 
xbORby or xb .OR. by 

The permissible relational operators are: 

DEFINITION 

Greater than 

Greater than or equal to 

Less than 

Less than or equal to 

Equal to 

Not equal to 

Logically greater than 

Logically greater than or equal to 

Logically less than 

Logically less than or equal to 

Logically equal to 

Logically not equal to 



RELATION 




bGTb 


or 


b .GT. b 


bGEb 


or 


b .GE. b 


bLTb 


or 


b .LT. b 


bLEb 


or 


b .LE. b 


bEQb 

bNEb 


or 
or 


b .EQ. b 

b .NE. b 


bLGTb 


or 


b .LGT. b 


bLGEb 


or 


b .LGE. b 


bLLTb 


or 


b .LLT. b 


bLLEb 


or 


b .LLE. b 


bLEQb 
bLNEb 


or 
or 


b .LEQ. b 
b .LNE. b 


The] 


permissible arith 


+ 


addition 




subtraction 


* 

/ 


multiplication 
division 



Where parentheses are omitted, the hierarchy of 
operations is as follows: * and /; + and — ; relational 
operations; not; and; or. 

Following are some examples of the if statement: 

IF (B EQ A*3.5) DUMP X, Y, Z 
IF A(I, I-J) EQ 3.4E2*QSUM DUMP X 
IF (X .EQ. 3 .AND. Z .LT. 24) GO TO 3 
IF LOGVAR .AND. 

(ALPHA+6 LE BETA OR LGVAR1) RETURN 

ON Statement 

The on statement is a count-conditional statement that 
permits the programmer to control the time when a 
debugging action is to be taken. It is similar to the 
Fortran iv logical if statement and is of the general 
form 

ON [(x)] ai, a 2 , as s 
where the ai are any arithmetic expressions (if they are 
not integral, they will be truncated); x is a unique sym- 



hoi, which should not be contained in the debucoinc 
dictionary, that represents a counter name; and s is an 
unconditional executable statement or an if statement 
followed by an unconditional executable statement. 
Additional information about the debugging diction- 
ary is provided in the publication IBM 7090/7094 
IBSYS Operating System: IBJOB Processor, Form C28- 
6275. 

The on statement is defined as true the aith time it is 
executed and every a 3 th time thereafter until a 2 is ex- 
ceeded. If a 2 is null, the statement is true the aith time 
and every a 3 th time thereafter. If a 3 is omitted, it is as- 
sumed to be one. If both a 2 and a 3 are omitted, the 
statement is true only the aith time. 

If x is specified, it creates a named counter for the 
on statement and x may be used in any computation 
or test, the same as any other variable, and may be 
named in other on statements. If the same counter is 
used by several on statements, it is incremented for 
each one of the on statements that is executed. Thus, 
the counter can be set and reset to any desired value. 
Effectively, the statement on(ctr) ai, a 2 , a 3 s is the 
same as the statements 

NAME CTR/ = NEW(X) 



SET CTR = CTR + 1 
IF (CTR GE ai AND CTR LE a 2 
AND ((CTR-aO/aa) *a 3 EQ CTR- 



-a,) 



All references to x are taken as references to this 
counter. Therefore, if x is duplicated by a symbol in 
the debugging dictionary, it will not be possible to 
refer to that object program symbol in a request. 

If x is not specified, an unnamed counter is created 
internallv. This counter is distinct from am 7 other 
counter. 



imp Ok txiQ quantities 



DUMP Statement 

The dump statement causes the du 
which are to be printed as debugging output. It is simi- 
lar in structure to the Fortran iv write statement and 
is of general form 

DUMP List 
where list is a series of items that are either direct ref- 
erences to the data to be dumped or the statement 
number(s) of list statements specifying the data to be 
dumped. The acceptable data specifications for either 
direct references or list statements are itemized under 
the discussion of the list statement. 

The dump statement causes information to be written 
on sysck2. The postprocessor edits the data on sysck2 
and writes it on sysoui. The formats supplied for the 
items of the dump statements are as follows: 

1. The symbolic reference of the item along with its 



relative and absolute locations and deck name is writ- 
ten to identify the debugging output. 

2. The value(s) of the item is written. The format, 
which is based upon the number of elements in the 
item and the mode of the item, is derived as follows: 



TYPE 

Octal 
Symbolic 
Instruction 
Symbolic 
Command 
Floating- 
Point 

Fixed-Point 
Double- 
Precision 
Complex 
Logical 
Alphameric 



NO./LINE FORMAT 

4 op 4 xxxxxx xxxxxx 

2 ±x xxxxx x xxxxx op a,t,d 4 

2 ±x xxxxx x xxxxx op(n*) a„d* 

6 ±.xxxxxxxx±xx 

8 ±xxxxxxxxxxxx. (leading zeros dropped) 

4 ±.xxxxxxxxxxxxxxxxD±xx 

3 ±.xxxxxxxx±xx ±.xxxxxxxx±xxj 
8 .TRUE, or .FALSE. 

72 char xxxx...xxx 



tiii sratemenT 



The list statement specifies the storage areas and/or 
registers that are to be dumped; it is of the general form 

statement number LIST item 1, item 2, . . . 
where the statement number is a standard Fortran 
statement number of up. to five numeric characters 
(punched in columns 1-5) and the items denote the 
addresses of the quantities to be dumped. Any reason- 
able number of items may be specified; they are sepa- 
rated by commas. The permissible items are detailed in 
the following text. Except where otherwise indicated, 
the term "symbol" in the following items refers to a 
symbol that either appears in the debugging dictionary 
or is defined in a name statement. The mode of the 
data dumped is determined from the debugging die- 

i.j.vyj.±ttj. y \j± nuiu Lil«_- i-\rvivj.iL aiaiciiimi, ±i tliia lull kjL ilia. uuil 

is not available, the dumps will be octal except where 
the mode is specified as in item 2 in the following text. 

The permissible items are: 

1. quantity — This may be one of the following: 

symbol This causes the array, the double-precision float- 

ing-point number, the complex number, or the 
single word denoted by this symbol to be 
dumped. 

This causes the array element, the double-pre- 
cision floating-point number, the complex num- 
ber, or the single word denoted by this sub- 
scripted symbol to be dumped. Any symbol may 
be singly subscripted, but only those symbols 
that have been dimensioned may have more 
than one subscript. The subscripts may be any 
arithmetic expressions. The mode of the dump 
is the same as the mode of the symbol. If 
ALPHA(6) is specified, the contents of the loca- 
tion ALPHA+5 is dumped except where 
ALPHA is double precision or complex, in 
which case ALPHA+10 and ALPHA+11 are 
dumped. 

4 op (n*) a, t, d refers to the symbolic representation of a machine langu- 
age instruction. This is primarily of interest to the MAP programmer. 
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symbol 
(subscript(s)) 



symbol ± n This causes the single word denoted by this 
quantity to be dumped. Symbol is as defined 
in the preceding text and n is an unsigned deci- 
mal integer. The mode of the dump is deter- 
mined from the referenced location and is not 
necessarily the same mode as the symbol. 

— Rn This causes the word at relative location n, 

where n is an unsigned octal integer, to be 
dumped. Only one word is dumped, even though 
it may be part of a double-precision or a com- 
plex number. 

—An This causes the word at absolute location n, 

where n is an unsigned octal integer, to be 
dumped. Only one word is dumped, even though 
it may be part of a double-precision or a com- 
plex number. 

The map programmer is referred to the sections 
"Quantities Available for Use in Debug Request State- 
ments" and "Address Computation" for more complex 
ways of addressing quantities. 

2. (loci, loc2 [, m]) — This causes the region from 
loci through loc2 to be dumped in the format m. Loc is 
any of the quantities previously defined or a statement 
number within the source program. If m is specified, it 
overrides any other mode designations given for the 
quantities involved. If m is not specified, the region is 
dumped in the mode(s) of the item(s) in the region. 
These modes are supplied in the debugging dictionary 
or name statement. The permissible values of m are: 



O 

S 

c 

F 
X 
D 

J 
L 

H 



Octal 

Symbolic instruction 

Symbolic command 

Floating-point number 

Fixed-point number 

Double-precision floating-point number 

Complex number 

Logical 

Alphameric 



Thus, (loc3(6), loc4(s,4), f) causes loc3 + 10 
through LOC4+H to be dumped in floating-point mode 
if LOC3 is a double-precision array and loc4 is a float- 
ing point array with dimensions of (3, 10). (6, =Ri27) 
causes the region from statement number 6 through 
relative location 127 8 to be dumped in the mode(s) 
supplied by the debugging dictionary or name state- 
ment. (akrayi,array2,x) causes all of arrayi, all in- 
tervening locations, if any, and all of array2 to be 
dumped in the fixed-point decimal mode. 

3. (data list, range) — This causes selected elements 
of arrays to be dumped. Data list may be one of the 
following: 



symbol (subscript(s)) 
(data list, range) 
data list, data list, . . . 



e.g., (A(I), I = 1, 4) 
e.g., ((B(L J), I = 1, 4), J = 1, 3) 
e.g., (A(I), (C(J, I), J = 1, 9, 2), 
D(I), I = 1, 4) 



Any arithmetic expression may be used as a sub- 
script. If the expression is not integral, it will be trun- 
cated. 



Range is of the form 
v = ai, a 2 [, as] 
where v is any symbol and the ai are arithmetic expres- 
sions. If the same symbol appears elsewhere in the pro- 
gram or in another debug request, that use(s) will be 
ignored for this statement. The dumps specified by the 
data list are taken for the value of v, namely a x through 
a 2 in increments of a 3 , or increments of one if a 3 is 
omitted. The maximum depth to which ranges may be 
nested is three. The following example of element spec- 
ification is invalid because it contains four nested 
ranges: 
((((A(L J, K), B(I, J, L), I = 1, 2), J = 1, 2), K = 1, 2), L = 1, 2 ) 

The following are valid examples of this element 
specification: 
(A(I,I),I = 1,3) 

dumps An, A22, A33. 
(B(I,6-I), 1 = 1, 5,2) 

dumps Bis, B33, Bbi. 
((A(I, J), I = 1,3), J = 6, 8, 2) 

dumps Aw, A26, A36, Aw, A28, Ass. 
((C(2*J-4, 10-3*1), 1 = 1, 3), J = 3, 4) 

dumps C27, C24, C21, C47, C«, C«. 
(A(J, J), (C(2*J-4, 10-3*1), 1 = 1, 3), J = 3, 4) 

dumps A33, Cw, C24, C21, A«, C47, C«, C«. 

The statement 
DUMP (A(I, J), 1 = 1,4) 
dumps a(ij), a(2,j), a(3,j), and a(4,j), where j is a 
variable previously defined either in the source pro- 
gram or in a name statement. 

4. // or /control section name/ — This causes blank 
common or the control section named to be dumped. 

// ±n or /control section name/ ±n — This causes 
the location at the beginning of blank common ±n or 
the location at the control section ±n to be dumped. 
Fortran labeled common names are control section 
names. 

5. program — This causes the entire object program 
exclusive of library subroutines to be dumped. 

6. msg' — This causes the message to be printed as it 
appears, msg is any message not containing a quotation 
mark; however, the external quotation marks are re- 
quired. 

To allow for interdeck communication, any item or 
set of items may be qualified with an associated deck 
name by preceding it with the deck name and two con- 
necting dollar signs, as follows: 

deckname$$item 

or 
deckname$$(item, item, . . . .) 

For example, a$$b refers to symbol b in deck a and 

the statement dump ab$$(bb,cb,(rb,sb,o)) dumps items 

bb, cb, and the octal region rb through sb in deck ab. 

NAME Statement 

The name statement permits the programmer to define 
symbols for use within debug requests and to supply 
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modal and/or dimensional information for the symbols. 
This definition overrides any other definition or any 
other associated information for the symbol within de- 
bugging text. The form of the name statement used 
primarily by the Fortran programmer is 

NAME symbols./ = NEW [^mode ^dimensions)] ^] [, svmboL...] 
where the parameters are defined as follows: 

symbol, Any valid FORTRAN symbol. 

=NEW =NEW specifies that a location of octal format 

or an area corresponding to the specified mode 
and dimensions is generated for the symbol. 

mode Mode can be either X, F, D, J, H, or L. These 

(dimensions) are defined in the section "The List Statement." 
The dimensions are the same as the dimensions 
specified by a DIMENSION statement. 

The name statement in the request must precede any 
references to the symbols it defines. 

Debugging Dictionary 

The debugging dictionary is a communication device 
between the program that is being debugged and the 
debug package. This dictionary contains symbols and 
pertinent data about the symbols, such as their relative 
locations, their modes, and their dimensions. It also 
contains Fortran statement numbers and their relative 
locations. If requested by the programmer on a $ibmap 
or a $ibftc control card, the debugging dictionary is 
produced by ibmap. Further information about the de- 
bugging dictionary is contained in the publication IBM 
7090/7094 IBSYS Operating System, IBJOB Processor, 
Form C28-6275. -J .. ,[ ,. * ^ 

A FORTRAN IV Load-Time Debugging Packet 

Figure 2 is the program main, and Figure 3 is the sub- 
routine SUBR. 



ClfENSICN ARRAYA15) 

BETA=1.2 

CO 25 1=1,3 

25 CONTINUE 

DC 26 1=1,5 
K=I 
CALL SUBR! ARRAYA.K) 

26 CONTINUE 
STCP 
ENC 

Figure 2. Program MAIN 



Ficm 
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Inad-tii 



30 



SUERCUTINE SUBR{C,K) 
DIMENSION C(5) 

2=15 
CO 30 1=1,2 
C(K)=K+I«10 
CONTINUE 
RETURN 
ENC 



bugging packet. The $ibdbl card heading the packet 
calls in the debugging compiler. Also, it specifies that 
all debugging activity is to cease when 450 debug re- 
quests have been executed at object time and that a 
maximum of 500 lines of debugging output is to be 
printed. 



678 



16-72 



$IBDBL TRAP MAX =450, LINE MAX = 50C 

•DEBUG MAIN 25 

NAME A/=NEW(F) 

ON 1 SET A=1.A 

IF BETA GE A RETURN 

CUPP BETA, 'BETA TOO SMALL.' 

SET A=A-0.1 
•DEBUG SUBR 1 

NAME X/=NEW(X) 

SET X=0 
•DEBUG SUBR 3C 

CN(X) 1,Z,3 DUMP «AIN$$ARRAYA 
• DEND 

Figure 4. Example of a FORTRAN IV Load-Time Debugging 
Packet 



The first debug request is executed at statement 25 
in deck main. The floating-point variable A is defined 
for use in the debugging request for deck main. The 
first time that statement 25 is executed, A is set to 1.4. 
beta (in program main) is tested each time prior to 
the execution of statement 25. If beta is less than A, 
beta is dumped, the message "beta too small" is 
printed, and A is decreased by 0.1. If beta is greater 
than or equal to A, return is made to the interrupted 
program. Then, statement 25 is executed. 

The second and third debug requests are executed 
at statements 1 and 30, respectively, in deck subr. Sup- 
pose that deck main calls subprogram subr several 
times and that statement 1 is the first executable state- 
ment in subr. Further suppose that subr contains a do 
loop that causes statement 30 to be executed many 
times. Under these conditions, the second request sets 
the counter X to each time that subr is called, and 
the third request dumps the array, arraya, in program 
main, the first, fourth, seventh, etc., time that state- 
ment 30 in subr is ci xe r>i ' , ''"' i d Th iic ^ r> ^ oo/->r>n/i p-n^ t-K-iwi 
requests trace the initial action of subr each time it is 
called. 

The *dend card terminates the action of the debug- 
ging compiler. 

Figure 5 is the output from the debugging postproc- 
essor that was obtained from the programs in Figures 
2, 3, and 4. 



Figure 3. Subroutine SUBR 



5 Logical accumulator may not be altered in a SET statement. 
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l f ••*•«*•• CUKP REQUEST AT A-754, REL LCC 00016, ABS LOC 02751, IN DECK HAIN 

<A-724,A-724,F) 

KAIN A + 44 

00054 03007 -724 +. 12CC0OO0+O1 
BETA TCC SHALL. 

2, »»**»»** CUNP REQUEST AT SUBR+46, REL LCC 0CC56, ABS LOC 03073, IN DECK SUBR 

(ARRAY A, ARRAY A+4.F) 

PAIN A +39 

00047 03002 -729 +.11000000+02 -. 61 6334C5-19 -.61833405-19 -.61833405-19 -.61833405-19 

3, •••«•••• CUHP REQUEST AT SUBR+46, REL LCC 00056, ABS LOC 03073, IN DECK SUBR 

( ARRAYA,ARRAYA+4,F) 

CAIN A + 39 

00047 03002 -729 +.21CC0C0O+02 +. 12C0C0C0+02 -.61833405-19 -.61833405-19 -.61833405-19 

4, •••••**• CUFP REQUEST AT SUBR+46, REL LOC CCC56, ABS LOC 03073, IN DECK SUBR 

(ARRAYA, ARRAYA+4.F) 

MAIN A + 39 

00047 03C02 -729 +.21000000+02 +.22C0C00C+02 +.13000000+02 -.61833405-19 -.61833405-19 

5, *»«««*.« CUMP REQUEST AT SUBR+46, REL LCC 00C56, ABS LCC 03073, IN DECK SUBR 

(ARRAYA,ARRAYA+4,F) 

HAIN A + 39 

00047 03002 -729 +.21CCCC00+02 +.22CCCC0C+02 +.23COO00O+02 +.14000000+02 -.61833405-19 

6, •••••••« CUCP REQUEST AT SUBR+46, REL LCC 0CC56, ABS LOC 03073, IN DECK SUBR 

(ARRAYA,ARRAYA+4,F) 

HAIN A + 39 

00047 03CC2 -729 +.21000000+02 +.22C0CCCC+C2 +.230O00C0+C2 +.24000000+02 +.15000000+02 

Figure 5. Example of the Output of the Debugging Postprocessor 



Additional Load-Time Debugging Features 

The following sections contain descriptions of addi- 
tional debugging facilities that are of interest mainly 
to the map programmer. They may also be used by the 
Fortran or cobol programmer. 

Quantities Available for Use in Debug Request Statements 

The quantities in Table i are available for use in the 
statements that make up the text of the debug request. 
Numerical constants may be used in arithmetic ex- 
pressions. A constant may be decimal floating point, 
decimal integer, or octal integer. If a number n con- 
tains a period, it is a floating point number; in this 
case, an e, ee, or d, followed by an exponent may be 
present, ee or d is used to indicate double precision 
floating point. If the first character of n (other than 
+ or — ) is a zero and n does not contain a period, an 
eight, or a nine, n is an octal integer and may be up to 
13 digits in length. Otherwise, n is a decimal integer. 



Complex constants are written in the form (ni, n 2 ), 
where n x is the real part and n 2 is the imaginary part. 
Although the machine representation is floating point, 
ni and n 2 can be octal, decimal, or floating point. 



Table I. Additional Quantities Available for Use in Statements 

QUANTITY MEANING 

=AC Accumulator (S, 1, 2, . . . , 35) 

=AC (ii — i2) Accumulator bits ix through i 2 ; 

^ ix ^ i 2 ^ 35; bit = S - bit 
=LAC 5 Logical accumulator (P, 1, 2, . . . , 35) 

^LAC 5 (ix — i») Logical accumulator bits ii through i 2 ; 

^ ii ^ it ^ 35; bit = P - bit 
=MQ Multiplier-quotient register (S, 1, 2, . . . , 35) 

=MQ (ii — i 2 ) Multiplier-quotient bits ii through i 2 ; 

^ i, ^ i 2 ^ 35; bit = S - bit 
=SI Sense indicator register (0-35) 

=SI (ii — i 2 ) Sense indicator bits ii through i 2 ; 

^ ii ^ i. ^ 35; 
=XRk Index register k; 

l^k^7 
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±j.it; fuiluwiiig are examples of numerical constants: =NEW 



0120 

129 

0129 

0.129E3 

(0120, -129) 



octal integer 

decimal integer 

decimal integer 

floating point 

complex, having true value 



Examples of the Logical IF Statement 

The following examples of the logical if clause make 
use of some of the quantities that refer to internal 
registers. 

IF(=SI(17)OR=SI(21)) 

IF (=SI (3-7) EQ 021) 

IF =XR4— 8 EQ 3*=XR2) 

LIST Statement 

One additional item that can be used in the list state- 
ment is available: 

console — This causes the contents of the accumula- 
tor, the multiplier-quotient register, the sense indica- 
tors, and the index registers, as well as the trapping 
and overflow indicators, to be written. 

Redefining Symbols 

The *redef card allows the user to change the names 
of symbols used in source decks to make them accept- 
able for use in debug requests. Included are symbols 
containing parentheses and map symbols that would be 
interpreted as numbers (e.g., o.ies, 4.6EE2, 633.D4, 1.2). 
The general form of the *redef card is 

1 8 16-72 

*REDEF deckname oldibASbnewi [,old 2 bASbnew 2 , . . .] 

where deckname is the deck in which the symbol to be 
redefined appears; b represents one or more blanks; the 
oldi are the symbols to be redefined; and the newi are 
me new names or tue svmuois. 

The variable field (columns 16-72) of a *redef card 
may be extended over more than one card by using the 
*etc card which is described in the section "Load-Time 
Debug Requests." 

*bedef cards, redefining symbols, must precede any 
use of the symbol newi. 

General NAME Statement 

The form of the general name statement is 

NAME symboli/ j^NEWC K mode [(dimensions)] )] 

[, symboL . . .] 
where the parameters are defined as follows: 

symboli Any valid MAP symbol not containing paren- 

theses, 
location A location designation as follows: 

1. A nonsubscripted symbol (plus or minus an 
integer, if desired). 

2. :=Rn, a relative location where n is an un- 
signed octal integer. 

3. =An, an absolute location where n is an un- 
signed octal integer. 



=iNJiw specmes tnat a location or octal format 
or an area corresponding to the specified mode 
and dimensions is to be generated for the symbol, 
mode Identical to those given in the section "Supply- 

dimensions) ing Modal Information to the Debugging Dic- 
tionary." 

The general form of the name statement may be 
used not only to define symbols for use within debug 
requests but also to -allow the use of symbols within 
the source program where no debugging dictionary, or 
an insufficient one, has been supplied. In addition, this 
form of the name statement supplies alternate modal 
and/or dimensional information to a symbol. 

KEEP Pseudo-Operation — For MAP Assemblies 

The keep pseudo-operation permits the programmer to 
specify a debugging dictionary that contains only those 
symbols he wishes to use in debug requests. The for- 
mat of the keep pseudo-operation is: 



NAME FIELD 


OPERATION 
FIELD 


VARIABLE FIELD 


Blanks 


KEEP 


One or more symbols, 
separated by commas 



The symbols in the variable field are entered into the 
debugging dictionary along with any modal and di- 
mensional information that was supplied in bss, bes, 
equ, and syn, pseudo-operations. Any number of keep 
pseudo-operations may appear in a program. If the 
nodd option was specified on the $ibmap card, the keep 
pseudo-operation is ignored. 

Qualified symbols may not be used in the variable 
field. If they occur, an error message is issued and the 
innermost name is used (e.g., a$b$c, c is used). If the 
same name appears in several qualification sections, 
the first encountered in the deck is used. 

Supplying Modal Information to the Debugging Dictionary 

ibftc supplies modal and dimensional information to 
ibmap and thence to the debugging dictionary auto- 
matically. However, the map programmer must supply 
this information himself in certain cases, i.e., when 
using bss, bes, equ, and syn. (Only modal information 

mav bft OIvpti with a TtF<!' rb'mpncirmal rlofa ic inmnra/1 "\ 

This information is specified in additional subfields of 
the variable field of these operations, as follows: 



NAME 
FIELD 


OPERATION 
FIELD 


VARIABLE FIELD 


Symbol 


/BSS ) 
JBES f 

(syn; 


Value 

[, mode [(di, d 2 , ds)]] 
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where symbol and value are the standard forms for 
these operations; mode is one of o, r, x, d, j, l, s, c, or 
h, as described in the discussion of the list statement; 
and di, d 2 , and d 3 are the dimensions 6 , if any, of the 
array denoted by the symbol. The following are exam- 
ples of these statements: 



A 


BSS 


25, F(5, 5) 


B 


EQU 


A+10, F(5, 3, 2) 


C 


SYN 


A+6, X 



Address Computation 

Address computation is a generalized form of indirect 
addressing. It is of special importance when complex 
tables or buffer chains must be manipulated. The nota- 
tion for address computation is: 
:=C (base address, opl, op2, . . .) 
Address computation is essentially a set of chaining op- 
erations. Each operation acts on the result (called the 
effective address) of the preceding operation. Any 
address ( e.g., a statement number, x, sym(i+s), =rio, 
=A703, but not x+3) can be used as a base address, and 
any machine register can be used as a base address if 
an extraction operation follows. The extraction opera- 
tions are (ii~ i 2 ), addr, and decr, where 0^iii=i 2 =35. 
The operation ( i x — i 2 ) extracts bits i x through i 2 of the 
word located at the address specified by the preceding 
operation; the bits thus extracted become the address 
used by the next operation. If i 2 — ii+l>15, only the 
rightmost 15 bits are used, addr and decr are short 
forms of (21-35) and (3-17), respectively. Thus, 
=c(a,addr) denotes the address portion of a. 

The operation compl complements the current ef- 
fective address to form the next effective address. 

The operators +,—,*, and /, have special meanings 
as shown in the following examples using the opera- 
tor +: 



+A 


means "add the address of A." 


+A,+B 


means "add the address of A, 




then add the address of B." 


+A+B 


means "add the value found by 




adding the contents of A to the 




contents of B." 


+n 


( where n is an integer ) means 




"add the value n." 



Thus, =c(a, +b) is the address of a plus the address of 
b, while =c(a, + b+o) or =c(a, +=c(b)) is the address 
of a plus the contents of b. Subtraction, multiplication, 
and division work similarly. 

The following are examples of address computation: 



=C(A) 

DUMP=C(A) 
SET =C(A) = = 
=C(A, ADDR) 

The statement 



the address of A 
same as DUMP A 
:C(B)+2 same as SET A = B+2 

the address portion of the word 
at address A 



dumps (in octal) the word whose location is specified 
in the address portion of the word at location a. 
Suppose that a contains 
PZE B, , 12 
then the statement 

DUMP ( =C(A, ADDR), 

=C(A, ADDR, +=C(A, DECR), -1)) 

dumps b through b+ii. 
The statement 
DUMP =C(A, +B) 
dumps the contents of the location computed by add- 
ing the address of a to the address of b. This is usually 
only meaningful if one of these addresses is absolute 
(i.e., not a relative value that is adjusted by the Loader). 
The statement 
DUMP =C (=A3, -=XR4) 
or the statement 

DUMP =C(=A77775, +=XR4, COMPL) 
dumps the contents of the word at three plus the com- 
plement of index register 4. 
The statement 

DUMP =C(3, -=XR4) 
dumps the contents of statement number 3 plus the 
complement of index register 4. 

Bit Extraction 

In arithmetic expressions (e.g., in set, if, call, and on 
statements and also in address computation and in sub- 
scripts), it is convenient to be able to handle partial 
word operations. The notation to be used is 

=C(address computation) (bit specification) 

or 
=mr(bit specification) 

where the bit specification is ii~i 2 , addr, or decr, with 
0^ii^i 2 ^35. mr denotes ac, lac 7 , mq, si, or xrL The 
notation 

=mr(i) 
where 0^i=35 is also permitted. 

The following are examples of partial word opera- 
tions: 



=C(A)(DECR) 

=C(A)(18-20) 

=AC(0) 

=SI(17) 

=C(=AC)(18-20) 

The statement 



the decrement portion of A 

the tag of A 

the sign of the accumulator 

bit 17 of the sense indicators 

invalid 



DUMP =C(A, ADDR) 



6 Arrays are structured and referenced as in FORTRAN. 



SET =C(A)(DECR) = =C(B)(18-20)+6 
replaces the decrement of the word at a with the sum 
of 6 and the tag of b. 
The statement 

IF =SI(4-7) EQ 012 SET =AC(ADDR)=Q 

7 The logical accumulator may not be altered in a SET statement. 
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replaces the address portion of the accumulator with 
the address portion of the word at Q (the rest of the 
accumulator is not affected) if sense indicator bits 4 
and 6 are 1, and bits 5 and 7 are 0. 
The statement 

DUMP A(=C(B)(iO-i7)) 
dumps the j th element of the array a, where j is the 
number found in bits 10 through 17 in the word at loca- 
tion B. 

A MAP Load-Time Debugging Packet 

The numbers in the left-hand column of the example 
in Figure 6 are for purposes of reference in the explana- 
tions that follow; they are not part of the requests 
themselves. The numbers in the first line across indi- 
cate the card columns in which the various fields begin. 

The $ibdbl card heading the packet specifies that all 
debugging activity is to cease when 1,000 requests have 
been executed and that a maximum of 500 lines of de- 
bugging output is to be printed. 

The first request is executed the first time and each 
time thereafter up to but not including the eleventh 
time that statement number 34 in decka is to be exe- 
cuted. This request specifies that the elements in list 
statement numbers 2 and 3 { which appear later in the 
packet) are to be dumped. 

The second request is executed prior to each execu- 
tion of statement number 42 in decka. It tests the value 
of a-b*c against 3.5*d and returns to the interrupted 
program if they are not equal. If they are equal, it 
dumps the range (in complex number format) from 
U through V ( if V is an array, the whole array will be 
dumped), dabbay 1; 7> 3 , and the message a-b<c eq 3.5 -d 
caused program stop. Program execution then stops 
and the postprocessor is called. 

The second request also contains list statement 
number 3, which, when used in a dump statement, 
causes the following information to be dumped: 

ALPHA 8> !, ALPHA 8 , 2 ,ALPHA 9 , i, ALPHA 9; 2 , • • • , ALPHAn, 2 ; 

all of the elements of barray; and all of blank 

COMMON. 

The third request is executed prior to each execution 
of the instruction at start+i" in deckb. On the third, 
sixth, ninth, twelfth, fifteenth, and eighteenth times 
that variable logvar is true (i.e., nonzero) the follow- 
ing win uc uurnpeu.; /\; control section cntrla; tiie 
region from relative locations 6 through 103 8 , in octal Figure 6. Example of a MAP Load-Time Debugging Packet 



format; tmu tue elements in LISi statement xiuuiuci t, 
which is contained in another debug request. 

The fourth request is executed on the hundredth time 
that statement number 34 in decka is to be executed: at 
all other times, it simply returns control to the inter- 
rupted pro°Tam. The information dumped consists of 
the console registers and indicators (list statement 
number 2 ) and the elements specified in list statement 
number 3, which is contained in the second request. 

The fourth request also contains list statement num- 
ber 4, which, when used in a dump statement, causes 
the principal diagonal of the matrix carray (in decka) 

The fifth request is executed the first time and every 
second time thereafter through the ninth time that the 
instruction at restrt in deckb is to be executed. It tests 
variable Q and, if Q is negative, dumps the elements 
in list statement number 2 (which is contained in the 
fourth request); the message q less than o; and the 
elements in list statement number 6, which specifies 
the region from restrt through restrt + ioo in sym- 
bolic format. 

The sixth request is executed prior to each execution 
of statement numbers 37 and 42 in decka. If A is less 
than B, it simply returns control to the interrupted pro- 
gram; otherwise it dumps a, b, e 1? e 2 , and e 3 . 

1 678 16-72 



SIBDBL TRAP HAX=1000, LINE MAX =500 

*DEBUG DECKA 34 

ON 1,10 DUMP 2,3 
•DEBUG DECKA 42 

IF A-B*C ME 3.5*0 RETURN 

DUMP (U,V,J),3ARRAY{1,7,3), 
X »A-B*C EQ 3.5*0 CAUSED PROGRAM STOP' 

STOP 
3 LIST ((ALPHA(I,J),J»1,2), 1=8,11), 

X BARRAY,// 
•DEBUG DECKB START+17 

IF (LOGVAR) OS 3,18,3 DUMP X, /CNTRLA/, 
X [=R6,=R103,0),4 
•DEBUG DECKA 34 

ON 100 GO TO 10 

RETURN 

DUMP 2,3 

STOP 

LIST CONSOLE 

LIST (CARRAYd, I ),I = 1,10) 
♦DEBUG DECKB RESTRT 

ON 1,10,2 IF 3 LT 0.0 OUMP 2, 
X *Q LESS THAN 0«,6 
6 LIST (RESTRT, RESTRT+100, S) 
•DEBUG DECKA 37,42 

IF (A .LT. B) RETURN 

DUMP A,B,(E(J) , J=l,3) 
• DEND 
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